StoryCam Session Chapter

第几章待补充：生成链路打磨与发布前门禁

这一章记录 StoryCam 从“能生成”走向“生成链路可信”的过程：最近项目恢复、输入页体验、参考图流程、分镜连续性、模型配置、下载体验和 Ship Gate 被串成一条可学习的产品工程路线。

TL;DR

最近项目从“小模块”变成关键入口

用户反复指出 /api/storycam-sessions/recent 500、刷新后加载失败、弹窗无法稳定打开。这个问题不是列表展示，而是保存、恢复、继续创作闭环是否可信。

四个主界面的视觉层级被统一

字体大小、状态小图标、模型选择板块、状态页 loading 都被用户逐个指出。Codex 将它们收敛为“导演工作台必须稳定、轻、可扫读”的界面原则。

手绘旅行 VLOG 明确为“真实场景 + 手绘角色”

用户提供教程截图和参考图，强调不要用 Codex 改过的图，要用原图。由此明确：风格图提供笔触，用户照片提供人物，旅行场景必须保持真实。

9:16 不是 UI 标签，而是生成链路参数

用户选 9:16 后发现风景图仍像 16:9，说明比例没有贯穿输入、景图、分镜、视频和预览。这个反馈推动了画幅约束的端到端对齐。

分镜问题从“图像质量”升级为“连续性质量”

紫色花位置、相邻景别、同一场景连续出现，让问题从单张图好不好看，变成一组镜头能不能剪、能不能讲故事。

发布前门禁被制度化，但本 session 未完成 ship

用户要求建分支并执行 gstack-ship。Codex 启动了流程，确认 base 为 dev，但用户随后中断。本章不能记录为已 PR、已 CI 或已 deploy。

本章学习目标

学会把 UI 反馈翻译成产品原则

例如“下箭头不在一行”不只是排版 bug，它说明用户已经进入验收态，基础控件必须减少认知摩擦。

学会调试生成产品的单位对齐

画幅、模型、参考图、语言、状态都不是孤立字段。它们要从输入页一路传到 provider、预览、保存和导出。

学会把生成质量问题拆成资产、镜头和序列

角色不像、场景不真、物体穿帮、景别重复分别属于不同层次，不能用同一种 prompt 硬修。

学会选择测试强度

小改快检、局部回归、交付门禁是三种反馈循环。开发时要快，发布时要全，二者不能混用。

工具、参考图和可视化证据

本 session 里有大量截图用于表达 UI 问题和生成质量问题。聊天截图本身未作为项目文件落盘，所以下面只嵌入项目中已有的参考图；其他截图按证据意义描述，不臆造图片细节。

手绘旅行角色风格参考图

手绘旅行角色风格参考图
这张图对应用户反复强调的“用我给你的原图 / 参考这种风格”。它在流程中的意义是：作为 Image 1 的风格参考，而不是替代用户照片或生成后的角色图。

截图证据：主界面字体与状态

用户提供四个 StoryCam 主界面的截图，指出标题、副标题、步骤标签、状态小图标不一致。这里的视觉证据用于说明“同一个产品流程的层级必须一致”。

截图证据：上传交互与画幅选择

用户对比了当前上传照片卡片和参考产品的输入框内缩略图交互，并指出 16:9 不能选、9:16 没有传到后续风景图。这是典型的“前端状态没有进入生成链路”的证据。

截图证据：分镜穿帮与镜头节奏

用户通过紫色花在不同图里的位置变化、相邻镜头景别过近，指出场景资产和镜头编排不足。这张证据把讨论从“再生成一张图”推进到“建立分镜选择策略”。

使用到的 Skill / 工具

code-simplifier 用于要求代码简化与一致性；imagegen 用于 favicon；gstack-ship 用于发布前门禁；浏览器 DevTools 截图用于复现最近项目加载失败；终端用于 git 分支、状态和测试线索。

安全处理

provider 错误、模型配置、签名 URL、token、真实用户素材都应脱敏。本章只保留错误类别和决策意义，不保留原始 provider payload 或任何 secret。

沿时间排列的原始 Prompt

这里保留最能体现需求变化和产品判断的用户原话。每组后面都有教师批注，说明它为什么是转折点。

01. 最近项目 500 与恢复体验
“GET /api/storycam-sessions/recent?limit=5 500 ... 为什么这么多 500”
“http://localhost:3000/storycam/input，每次刷新或者跳转会这个页面时，‘最近项目’都要刷新一会，这是为什么？有什么更好的办法”
“为什么刷新页面会会有这么一个状态页，而且会卡很长时间，需要找个更好的方式”
教师批注：这是本 session 的工程起点。用户没有只说“接口报错”，而是把错误和体验连接起来：刷新、跳转、恢复、最近项目都在同一条用户路径上。调试时要沿用户路径查，而不是只看一个 API。
02. 主界面一致性与状态去噪
“这四个主要界面的不同层级的字体大小不一致。”
“这三个界面框出来用来表示状态的小图标都去掉。”
“这个模型选择也是跟输入页的尺寸选择一样，要用一个按钮，点击才出来即可，不要把整个板块布局拉高了。”
教师批注：这类 prompt 看似是 UI 细节，实则是产品成熟度信号。用户开始在意层级、节奏、密度，说明基础流程已经能跑，下一步要减少界面噪音，让产品像一个整体。
03. 手绘旅行 VLOG 参考图流程
“手绘旅行VLOG 风格，图生图，人物资产有问题，剧本有了后生成好像是失败，点了重新生成没有轮询，不知道是否成功。”
“传的那张参考图是什么，这个过程是需要一个参考图的，你可以让我看看是不是截图里的。”
“是这种参考图，你看看怎么加在流程中。”
“你不要放你改的图呀，用我给你的原图。”
“要参考这个。”
教师批注：这是参考图语义的澄清。AI 产品常见错误是把“参考风格图”“用户真实照片”“生成结果图”混成一个概念。用户在这里强制分清输入来源，这是后续生成质量稳定的前提。
04. 上传交互、画幅比例和中文输出
“上传照片这个交互太难看了，我希望像图 2 中的交互，上传的图片加到输入框里展示，然后 16:9 是能选的，现在选不了。”
“我现在选的是 9:16，我发现后面生成的风景图还是 16:9 的，这个地方要注意。”
“分镜脚本等生成希望是中文的。”
“如图 ui 有问题，下箭头应该和字母在一行。”
教师批注：这组 prompt 体现了“前端选择必须影响后端生成”的单位对齐。画幅、语言、控件排版都不是装饰，它们决定用户是否相信系统理解了自己的选择。
05. 分镜场景、景别和连续性
“现在这个vlog 模式下分镜图生成的也有问题，如图中所示，场景不是真实实际场景了，这个参考的方式如图 2。”
“分镜图这块好像有些冲突，如图 2 和图 3 里的紫色花都不在一边，感觉场景资产用的不够好，致使后面的视频有些场景上的穿帮。”
“一样的镜头别老连着放；相邻的镜头也别硬凑在一起；景别差别大、反差明显的镜头接起来，看着才舒服、流畅。”
“分镜那块还需要进一步迭代：避免连续同景别及相邻景别。”
教师批注：这是本章最重要的产品判断。用户不是要求“图片更漂亮”，而是要求镜头之间有剪辑逻辑。对于 AI 视频产品，核心质量单位是镜头序列，不是单张图。
06. Provider、最近项目、下载和发布
“env 里我刚刚配置上了SEEDANCE_FAST_MODEL。”
“这个最近项目里会保存几个？当达到一定数量时要支持滚动查找，通知支持删除功能；点击继续创作统一跳转到该项目的‘故事世界’板块。”
“最后生成好视频后，点击下载 mp4 还需要调到一个原生播放器界面再加下载很复杂，要优化 ux。”
“特别核心的思路是不是放在 Agents.md 里面也可以？”
“建个分支，然后 gstack-ship。”
教师批注：这组 prompt 把产品体验、工程配置、文档制度和发布流程连起来。好的 AI 开发不是只修当前 bug，而是把经验沉淀到项目规则和发布门禁里。

时间线

T01
用户原话 “为什么这么多 500”
Codex 总结 Codex 将最近项目 API 的 500 放到 session restore 链路中分析：问题不只是接口失败，也包括刷新输入页时重复拉取、恢复态阻塞、前端缺少可用缓存和容错反馈。
结果 / 影响：最近项目被定义为 StoryCam 的核心入口问题，后续需要 API 测试和 e2e 恢复测试共同覆盖。
T02
用户原话 “好的，你迁移一下。”
Codex 总结 用户接受迁移方向后，Codex 开始把最近项目加载从同步等待改成更轻的恢复模型：前端可先显示已有内容，后端查询失败要降级而不是拖垮页面。
结果 / 影响：修复方向从“接口修到 200”扩展到“页面可恢复、可继续创作”。
T03
用户原话 “这四个主要界面的不同层级的字体大小不一致。”
Codex 总结 Codex 将核心前提、故事世界、核心分镜、片段生成四个页面的标题、副标题、步骤文本和按钮层级统一，避免用户感觉每一步来自不同产品。
结果 / 影响：StoryCam 的主流程获得一致的视觉节奏，后续 UI 修改有了可遵循的字体层级。
T04
用户原话 “这三个界面框出来用来表示状态的小图标都去掉。”
Codex 总结 Codex 移除英雄区右侧用于表达状态的多余小图标或 pill。状态不应抢占主标题区，真正需要的状态放在操作区或卡片内。
结果 / 影响：页面第一屏更聚焦“当前任务是什么”，而不是被装饰性状态分散注意力。
T05
用户原话 “模型选择也是跟输入页的尺寸选择一样，要用一个按钮，点击才出来即可。”
Codex 总结 Codex 把模型选择从展开的板块改成按钮触发的菜单，沿用输入页尺寸选择的交互，避免生成页底部操作栏被模型选项撑高。
结果 / 影响：生成动作、模型选择、完成状态形成一个紧凑操作带，减少布局跳动。
T06
用户原话 “有 code review”，“记得回复 review”，“已经 merge，可以更新本地代码。”
Codex 总结 这段进入协作流：Codex 需要处理 review、回复 review、跟进 merge 后的本地同步。项目不再是单次代码生成，而是持续交付。
结果 / 影响：StoryCam 的工作方式形成“实现 -> review -> 回复 -> merge -> 本地更新 -> 继续迭代”的节奏。
T07
用户原话 “手绘旅行VLOG 风格，图生图，人物资产有问题...点了重新生成没有轮询，不知道是否成功。”
Codex 总结 Codex 将问题拆成两块：人物资产生成的参考图输入不清，以及重新生成后的 job 状态轮询不完整。用户需要知道失败、排队、生成中、成功分别是什么。
结果 / 影响：生成状态必须可追踪，参考图必须被明确纳入流程。
T08
用户原话 “你不要放你改的图呀，用我给你的原图。”
Codex 总结 Codex 修正参考图使用原则：系统可以保存和传递用户上传的原图，但不能用自己生成或修改后的图替换用户原始素材。风格参考和人物参考要分开。
结果 / 影响：这是隐私和生成一致性的双重约束，避免用户私密素材被混淆或误替换。
T09
用户原话 “上传的图片加到输入框里展示，然后 16:9 是能选的，现在选不了。”
Codex 总结 Codex 将上传交互改向输入框内缩略图展示，并修正画幅选择控件。图片是输入的一部分，不应像页面下方的独立附件一样打断创作。
结果 / 影响：输入页更接近“写一句想法 + 放入照片 + 选画幅”的自然创作体验。
T10
用户原话 “我现在选的是 9:16，我发现后面生成的风景图还是 16:9。”
Codex 总结 Codex 将这个问题定位为比例参数没有贯穿全链路。选择 9:16 后，景图、核心分镜、扩展分镜、视频生成和预览都要尊重同一比例。
结果 / 影响：画幅从 UI 选项升级为生成契约。
T11
用户原话 “分镜脚本等生成希望是中文的。”
Codex 总结 Codex 将分镜标题、描述、音频提示等用户可见文本约束为中文。英文 prompt 可以存在于内部，但不应泄漏到普通用户界面。
结果 / 影响：StoryCam 的创作内容更适合目标用户阅读，也减少 prompt 工程痕迹。
T12
用户原话 “场景不是真实实际场景了，这个参考的方式如图 2。”
Codex 总结 Codex 将手绘旅行 VLOG 的视觉公式明确为：真实摄影风格旅行背景 + 二维手绘角色自然融合。场景不应该被整体转成插画。
结果 / 影响：旅行 VLOG 的资产生成从“风格化整图”改为“真实场景承载角色”。
T13
用户原话 “providerName: seedance_2_0_fast ... status: failed”，“env 里我刚刚配置上了SEEDANCE_FAST_MODEL。”
Codex 总结 Codex 将 Fast 模型失败和显示不一致联系起来：必须明确读取环境变量，并在 UI 与最终成片信息中显示真实模型，不能让用户以为选择被忽略。
结果 / 影响：provider 配置必须可诊断，错误详情要脱敏但类别要可见。
T14
用户原话 “点击继续创作统一跳转到该项目的‘故事世界’板块。”
Codex 总结 Codex 将继续创作的入口统一到故事世界，而不是直接跳到项目当前状态。这样用户回到项目时先确认世界设定，再进入分镜或生成。
结果 / 影响：恢复路径更符合 StoryCam 的 MVP loop：故事世界确认是进入后续生成的门。
T15
用户原话 “点击下载 mp4 还需要调到一个原生播放器界面再加下载很复杂。”
Codex 总结 Codex 将下载设计改向产品内直接导出。服务端需要代理媒体下载，避免浏览器打开原生播放器，也避免暴露签名 URL。
结果 / 影响：最终成片的导出体验从浏览器 hack 变成产品动作。
T16
用户原话 “紫色花都不在一边...致使后面的视频有些场景上的穿帮。”
Codex 总结 Codex 将问题定位为场景资产锚点不足。关键物体、角色方向、门窗位置、花的位置等要作为连续性约束进入分镜生成，而不是每张图独立发挥。
结果 / 影响：分镜生成需要维护“场景记忆”，否则视频阶段会放大穿帮。
T17
用户原话 “一样的镜头别老连着放；相邻的镜头也别硬凑在一起。”
Codex 总结 Codex 将镜头选择策略加入分镜逻辑：避免连续同景别及相邻景别，优先让景别差异、动作转折和视觉反差形成剪辑节奏。
结果 / 影响：分镜从“九宫格扩展图”向“可剪辑镜头序列”演进。
T18
用户原话 “小改先跑最近的确定性测试；行为边界变化跑相关 API/集成测试；交付前才跑全量门禁。”
Codex 总结 Codex 将测试策略沉淀为三档：小改快检、局部回归、交付门禁。核心思路放入项目规则，细节放入 docs，避免 AGENTS.md 变得臃肿。
结果 / 影响：StoryCam 的开发节奏更清楚，避免每次小改都跑全量，也避免发布时缺少门禁。
T19
用户原话 “最近项目加载失败”，“还是不行。”
Codex 总结 用户通过 DevTools 截图证明 recent?limit=20 仍失败或被取消。Codex 需要继续沿前端 abort、后端超时、历史坏数据解析和弹窗加载态排查。
结果 / 影响：最近项目仍是待确认事项，不能因为已有修复就宣称完成。
T20
用户原话 “建个分支，然后 gstack-ship。”
Codex 总结 Codex 启动发布前流程：创建发布分支意图，读取 gstack-ship 和 StoryCam Ship Gate 规则，检测 base 为 dev，准备跑确定性检查和三份 reviewer 报告。
结果 / 影响：用户随后中断。发布没有完成，所以不能记录 PR、CI 或部署成功。

关键时刻

关键发现：最近项目是信任入口

当时的问题
最近项目 API 500、刷新后反复加载、弹窗加载失败。
为什么重要
StoryCam 不是一次性生成玩具，用户需要回到旧项目继续创作。恢复入口不稳，保存就没有意义。
最终处理
方向转为缓存、容错、可滚动查找、删除、继续创作统一进故事世界；最终仍需复跑完整验证。

转折点：参考图职责被拆清

当时的问题
手绘旅行 VLOG 中，风格参考、用户照片和生成图容易被混用。
为什么重要
混用会导致人物资产不准，也会触发隐私和信任问题。用户明确要求用原图。
最终处理
风格图只提供笔触和画风，用户照片提供人物，真实旅行场景提供空间。

复盘笔记：比例是端到端契约

当时的问题
用户选了 9:16，但后续风景图仍像 16:9。
为什么重要
短视频产品的画幅会影响构图、分镜、预览和视频生成。比例错了，素材就难以复用。
最终处理
将画幅作为全链路参数，而不是只存在于按钮里的前端状态。

关键发现：分镜的单位是镜头序列

当时的问题
紫色花位置穿帮、连续镜头景别重复、相邻镜头硬凑。
为什么重要
后续视频生成会继承分镜问题。单张图好看，不代表剪起来流畅。
最终处理
增加场景锚点、避免连续同景别、避免相邻景别、参考 Shanyin 分镜技巧。

复盘笔记：发布不是“看着能用”

当时的问题
大量 UI、API、provider、下载、文档变更准备进入 ship。
为什么重要
跨层改动容易产生回归。StoryCam 规定 ship gate 需要确定性检查和三份评审。
最终处理
Codex 启动 gstack-ship，但被用户中断。结果应标记为未完成，而不是假装已发布。

关键决策表

议题 方案 当时看起来的好处 为什么放弃或保留 最终选择
最近项目加载 每次进入输入页都重新请求后端 实现直接，数据最新。 刷新和跳转会让用户反复等待；接口失败时整个模块变成噪音。 保留后端刷新，但引入缓存、容错和更轻的失败态。
恢复页状态 全屏显示“正在恢复上次故事” 状态明确，开发简单。 用户看到长时间卡顿，误以为页面挂住。 优先展示页面骨架，恢复在后台渐进完成。
模型选择 UI 展开整个模型板块 选项可见，不需要点击。 拉高底部操作区，影响“生成片段”主动作。 使用按钮 + 下拉菜单，和输入页画幅选择保持一致。
手绘旅行视觉策略 把整张旅行图都画成手绘 风格强烈，容易统一。 用户明确要求真实旅行场景；整图手绘会失去“真实 VLOG”感。 真实摄影场景 + 二维手绘角色自然融合。
画幅处理 只在输入页按钮记录 9:16 / 16:9 前端实现容易。 后续景图和视频仍可能用错比例。 画幅成为生成链路参数，贯穿景图、分镜、视频和预览。
MP4 下载 打开视频 URL，靠浏览器原生菜单下载 几乎不用做产品内下载。 体验复杂，并可能暴露签名 URL 或 provider 细节。 产品内直接触发下载，服务端代理媒体资源。
测试策略 每次小改都跑全量 心理上安全。 反馈慢，阻碍开发节奏。 三档测试：小改快检、局部回归、交付门禁。

可复用方法

AI 生成产品的“单位对齐”检查法

每个用户选择都问一遍：它是否进入了后端参数、prompt、保存数据、预览展示和最终导出。

  1. 列出用户可选择的单位：画幅、模型、语言、参考图、项目阶段。
  2. 沿链路追踪：输入页 -> API -> provider -> 结果 -> 保存 -> 恢复。
  3. 找出只停留在 UI 的字段，并补成生成契约。
生成质量的“三层拆解法”

不要把所有生成问题都归因于 prompt。先拆成角色资产、场景资产、镜头序列三层。

  1. 角色问题：人物不像、服装不一致、风格不稳定。
  2. 场景问题：空间不真实、关键物体位置变化、道具穿帮。
  3. 序列问题：同景别重复、相邻镜头硬接、缺少反差。
调试最近项目的“用户路径法”

不要只看 API 500。把用户路径串起来：打开输入页、恢复项目、查看最近项目、继续创作、删除项目。

  1. 先定位失败发生在哪个动作。
  2. 再看请求是否被取消、超时、解析失败或后端 500。
  3. 最后补前端缓存、后端容错、测试覆盖。
UI 打磨的“去噪优先”原则

当主流程已经可用时，下一步不是加更多提示，而是删掉不帮用户决策的状态、装饰和大段文字。

  1. 找出页面主动作。
  2. 把状态放到操作区，而不是英雄标题区。
  3. 长脚本改摘要，详情按需展开。
发布流程的“三档测试”

用测试强度匹配风险，不要把全量检查当开发内循环。

  1. 小改快检：跑最近的确定性测试文件或 case。
  2. 局部回归：跑相关 API / e2e，加 typecheck 或 lint。
  3. 交付门禁：全量 test、API、E2E、typecheck、lint 和 review。
敏感信息最小化记录法

复盘文档里保留错误类别和决策，不保留 secret、签名 URL、原始 provider payload 或用户私密素材。

  1. 错误写类别：request_rejected、404、provider 名可保留。
  2. 密钥、token、完整 payload 写 [REDACTED]。
  3. 用户图片只描述用途，除非已作为项目公开文件落盘。

工程证据

本 session 有工程操作线索，但用户中断了 gstack-ship，因此发布结果必须标记为未完成 / 未确认。

分支与发布

Branch
ship/storycam-flow-polish 曾被创建用于准备 ship；中断后当前分支状态需要重新确认。
Base
gstack-ship 检测目标 base 为 dev。
PR
not created / 未确认
Commit
未确认
Deploy
not run

测试线索

以下命令作为本 session 中出现过的验证方向记录，正式发布前必须复跑，不能当作最终门禁结果。

pnpm vitest run tests/api/sessionRestore.test.ts -t "GET /api/storycam-sessions/recent"
pnpm typecheck
pnpm lint
pnpm exec playwright test tests/e2e/storycam-restore.e2e.ts

Provider 诊断

症状
Fast 模型生成失败，错误类别为 request rejected，HTTP 状态为 404。
配置
用户补充已配置 SEEDANCE_FAST_MODEL。
记录策略
原始 provider payload、签名 URL、secret、token 均记为 [REDACTED]。

涉及文件面

聊天内容涉及这些区域，最终精确 diff 需以 git 为准。

  • src/app/api/storycam-sessions/recent/route.ts
  • src/components/storycam/*
  • src/server/storycam/*
  • src/lib/providers/openrouter/*
  • tests/api/* 与 tests/e2e/*
  • docs/* 与 AGENTS.md

工具与技能

  • code-simplifier：要求代码保持简洁、一致、可维护。
  • imagegen：用于生成并配置 favicon。
  • gstack-ship：用于发布前门禁，但流程未完成。
  • DevTools Network：用于证明最近项目请求失败或取消。

未产生的证据

  • 没有可确认的 PR 编号。
  • 没有可确认的 CI 结果。
  • 没有可确认的部署结果。
  • 没有可确认的最终 release / changelog entry。

后续事项

已完成

  • 明确最近项目是 StoryCam 的继续创作入口。
  • 明确手绘旅行 VLOG 的参考图分工。
  • 明确 9:16 / 16:9 必须贯穿生成链路。
  • 明确中文分镜脚本和用户可见文案的产品要求。
  • 明确测试选择策略：小改快检、局部回归、交付门禁。

待确认

  • 最近项目加载失败是否已在当前分支彻底修复。
  • Fast 模型配置和最终成片显示是否一致。
  • MP4 直接下载是否已通过真实媒体验证。
  • 9:16 竖版素材在核心分镜和片段生成页是否全部显示正确。
  • gstack-ship 中断后的当前分支和工作区状态。

后续开发

  • 复跑 StoryCam Ship Gate，产出 code-reviewer、security-auditor、test-engineer 三份报告。
  • 继续完善分镜选择策略，避免连续同景别和相邻景别。
  • 增加场景资产锚点，稳定紫色花、门、墙、角色方向等关键位置。
  • 继续压缩核心分镜页文字展示，让用户先判断画面和镜头。
  • 将本章记录和后续 session 串成完整项目开发讲解文档。

本章按当前 session 聊天内容整理。凡是没有在对话中明确完成的 PR、commit、CI、deploy，均标记为未确认或未运行。